Release 10.1A: OpenEdge Development:
Programming Interfaces

Using message digests in the 4GL

A message digest is the result of a one-way hashing operation that produces a unique value for a given unique string of data. Its primary use is to detect any unauthorized changes in data (verify its data integrity).

For example, suppose you have a database record with 10 sensitive data fields, and you need to determine if any of the fields have been unexpectedly changed. Before you create or update the database record you can hash the 10 sensitive fields into a single message digest and store the digest under the same record key. Each time you read the database record, you can check its data integrity by hashing the same 10 fields and compare the resulting message digest with the one currently stored for that record. If the two message digests do not match exactly, the data has undergone an unauthorized modification.

Securing a message digest

One property of message digests is that they are predictable, yielding the same result every time they are hashed from the same data. To help protect against someone recomputing the message digest along with an unauthorized change to the data, you can provide a secret key for the algorithm to hash a value that is unique to both the data and the key. This value is a type of message authentication code (MAC). You cannot easily recreate a MAC without knowing the secret key.

You can use any value for the key that you choose or use the built-in key generation functions to generate a key for you (see the "Generating encryption keys" section). If you store the secret key securely, like any cryptographic key, this results in a secure message digest.

Generating message digests in the 4GL

The 4GL provides two built-in functions to generate message digests using the following syntax:

Syntax

MD5-DIGEST | SHA1-DIGEST (data-to-digest [, secret-key-bytes])

The difference between these functions is the algorithm used to generate the digest. MD5-DIGEST uses the RSA Message Digest Hash Algorithm (MD5) and SHA1-DIGEST uses the United States Government Secure Hash Algorithm (SHA-1).

Both the data-to-digest and secret-key-bytes values accept CHARACTER, LONGCHAR, MEMPTR, or RAW values. If you use a CHARACTER or LONGCHAR, the function automatically converts the value to the UTF-8 code page before generating the digest, ensuring that the digest is code-page independent.

The result of each function is a RAW digest value that is 16 bytes long for an MD5 message digest and 20 bytes long for an SHA-1 message digest.

Managing message digests

If you want to hash multiple data sources (such as several database fields) into a single message digest, you can marshall the individual data sources into a single MEMPTR variable using the PUT-datatype functions before invoking the message digest function. To make this work correctly, you must marshall exactly the same data sources using exactly the same order and data formats to generate comparable digests.

Because message digests are generated as a RAW binary byte stream, you must ensure that the byte endian order is maintained cross different hardware platforms.

The management considerations for message digest keys and results is much the same as for any encryption keys and data, except that you do not have to keep track of the code page of data sources. For more information, see the "Managing and transporting crypto data" section.